docs(api): daily audit 2026-08-24 — align stale envelope schemas, fix template update semantics - #305

Summary

Daily api-review audit (2026-08-24). Deterministic audit performed directly on HEAD: registry public rows (337) match spec paths (337) in both directions, docs.json nav covers all 337 operations in en/zh, api-catalog counts (191/42/35/42/27 = 337) reconcile, en/zh structural parity holds, and scripts/lint_openapi.py is clean. No endpoint was added or removed — the two new fc-pgy registry rows are Auth: jwt (not public) and the rate-limit change is on an Auth: data row (also not public), so no docs.json / api-catalog.mdx changes are needed.

Two real drifts found and fixed:

1. Stale envelope schemas in consolidated + safari files (committed internal drift)

The canonical error envelope (ErrorCode / DutyError / ErrorResponse) matches the on-call / platform / monitors / rum split files and the generator's envelope_schemas() output exactly, but the consolidated openapi.{en,zh}.json and safari split still carried an older lean version:

• ErrorCode — missing x-enumDescriptions (per-code explanations), missing example, and a short description without the full code→HTTP table
• DutyError — message property missing its example; zh file carried English description text
• ErrorResponse (zh) — description in English instead of Chinese

Per the committed-internal-drift rule, the split files (what Mintlify renders) are the truth source; consolidated + safari are aligned back to them. en files: 2 schemas touched (ErrorCode, DutyError); zh files: 3 (ErrorCode, DutyError, ErrorResponse).

2. /template/update description stale vs backend semantics

fc-event merge 3e6c9763 (fix-template-update-patch-semantics, 2026-08-23) changed update semantics to partial-update: a channel omitted from the request is no longer cleared — only an explicit empty string clears it. The operation description "Replace the content of every channel on an existing template" described the old (buggy) behavior and is updated in on-call split + consolidated (en + zh):

• en: "Update an existing template. Channels you omit keep their content; send an empty string to clear one."
• zh: "更新已有模板。未发送的通道保持原内容，发送空字符串可清空通道。"

Note: the request schema's field-level descriptions remain valid (they describe the source format, not update semantics); only the operation description needed the fix.

Checks

• python3 scripts/lint_openapi.py — clean (12 spec files, no violations)
• All 13 spec JSON files parse
• Registry ↔ spec paths: 337 / 337, 0 unmatched in either direction
• Consolidated vs split: 0 content differences (paths + 707 schemas, en + zh)
• en/zh structural parity: 0 divergences across all 5 modules
• docs.json nav: 337/337 covered, en/zh identical
• sort-key deep compare vs HEAD per file: only the semantic changes above, no reordering

Scope

No operations added/updated/removed. Unresolved: none (no registry row lacked a handler; no new public rows). No constructed examples — no examples were synthesized this round.